=================
 SA Map Cleaner
=================
 Version 0.5 RC1
 2007-10-24
=================

Copyright © 2005-2007 by Steve M.

Email: support@steve-m.com
Web: http://www.steve-m.com


DISCLAIMER
~~~~~~~~~~

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

This program is not a public release and must not be distributed!

For the official release, keep an eye on
http://www.steve-m.com/downloads/tools/mapcleaner/

I am not associated with Rockstar Games, Rockstar North or Take Two in any way.


Archive Contents
~~~~~~~~~~~~~~~~

MapCleaner.exe         - the Map Cleaner application
ReadMe.txt             - this documentation
extras\emptypaths.zip  - empty path node files
extras\main.scm        - a minimalist mission script for testing
extras\main.txt        - the test script's source code
extras\testmap.zip     - a small test map made by DexX
extras\water.dat       - defines only one big water surface


Getting Started
~~~~~~~~~~~~~~~

Map Cleaner is used to automatically remove unneeded game objects from the GTA
San Andreas (PC) map, to make room for mods up to the size of whole new maps.

The tool will disable all item placement file entries (ipl) in gta.dat, as well
as the item definition file entries (ide) you chose not to keep. Those files
will be scanned, and all referenced model (dff), texture (txd), animation (ifp)
and collision (col) files that aren't shared with any of the other kept files
will be deleted from the game's archives (img).

If you want to install a map modification which instructs you to simply run
SA Map Cleaner, go by the following steps:

1. Backup

   Please note that the changes Map Cleaner does to your game installation
   can't be easily undone, so if you intend to play the original game again or
   install other mods, you should consider making a backup of your whole GTA
   San Andreas directory prior to starting the cleaning process.

2. Preparations

   Execute MapCleaner.exe, click the "Browse for Game Directory" button, and
   select the main directory of the GTA SA installation you want to clean.
   
   On the Objects page you will now see a list of .ide files, with a number of
   them already selected, some disabled. Those that are selected are the ones
   that will be kept, which are by default those for all sorts of generic
   objects. Unless the mod you're installing doesn't mention deselecting any
   of these, just keep them as they are to avoid potential problems with
   missing objects.
   
   The Settings page will give you a bunch of choices over how Map Cleaner
   operates, the most important of which is the "Rebuild archives" switch. If
   this is checked, all managed archives (gta3.img, gta_int.img and all
   additional archives defined in gta.dat except the default ones) will be
   rebuilt, i.e. all deleted files will be physically deleted (not just removed
   from the internal file index) so the archive will get smaller. This is still
   rather slow in this version, so you might want to switch it off.
   
3. Cleaning

   Press Start to initiate the cleaning process. After a few seconds you'll be
   asked to confirm applying changes to your files, which when answered with No
   will leave your game untouched. Otherwise the archive will be rebuilt (if
   enabled in the setting), which might take about a minute depending on number
   of files left and HDD speed.
   
4. Testing (optional)

   First of all, you will need to replace the mission script. Simply overwrite
   the old main.scm in data\script\ with the minimal one included in extras\.
   You could also delete script.img if you don't need any of the auxiliary
   scripts. (The source code of this script is in main.txt.) It will spawn you
   at the center of the map in a Hydra.
   
   Now the water surface will be full of holes since the solid land is gone. To
   get a single, closed surface replace data\water.dat with the file of the
   same name in the extras\ directory.
   
   Unless you are installing a map that comes with its own paths, you might
   find those cars hovering in mid-air along their old paths quite annoying.
   To overwrite the old paths with blank ones, replace the 64 nodes*.dat files
   in gta3.img with the contents of extras/emptypaths.zip.
   
   Also, in most cases the game will crash or hang when you try to run it
   without a map, so you have to install a few custom objects and it should
   work fine. For this purpose DexX has provided a small test map consisting of
   only two objects just below the spawning point of the test script. To
   install it, extract the contents of extras\testmap.zip to the data\
   subdirectory of your game, overwriting the existing gta.dat file. Please
   note that this will only work if you used Map Cleaner 0.5 with the default
   settings, otherwise you'll have to insert the following lines into gta.dat
   by hand (in the appropriate sections):
   
   IMG DATA\MAPS\basic\basicmap.IMG
   IDE DATA\MAPS\basic\basicmap.IDE
   IPL DATA\MAPS\basic\basicmap.IPL
   
   To remove this map again, delete or disable those 3 lines in gta.dat and
   delete the basic\ directory. Alternatively you can run Map Cleaner again;
   make sure basicmap.ide is not selected.

For more information, help, and background info, visit this forum thread:
http://www.gtaforums.com/index.php?showtopic=198101


Use Cases
~~~~~~~~~

[ to be written... ]


Information for Mod Authors
~~~~~~~~~~~~~~~~~~~~~~~~~~~

[ to be written... ]


Technical Information
~~~~~~~~~~~~~~~~~~~~~

[ to be written... ]


History
~~~~~~~

Version 0.5 RC1 (2007-10-24)
- redesigned user interface
- improved map parser (better handling of comments and missing commas)
- animation file handling (sections anim/cars/weap)
- collision file handling based on col models
- new archive manager supports multiple archives
- highly improved cleaning speed
- optional archive rebuilding (still slow)
- online update check
- redesigned log file, more logging options
- inverse ide selection (check to keep); seabed removed from default

Version 0.4 Beta 2 (2006-09-03)
- added debug logging

Version 0.4 Beta (2005-06-30)
- small bugfix
- new default settings
- updated main.scm (reduced memory)

Version 0.3 Beta (2005-06-22)
- first public test version

   
Acknowledgements
~~~~~~~~~~~~~~~~   

Thanks to:
- illspirit for helping me figure out how to get an empty map working
- DexX for providing a test map
- all the testers and people who gave feedback


If there are any problems, questions, mistakes, bugs or something else simply
send an email! (support@steve-m.com)

Enjoy

Steve